/*
 * ErrorCode.java
 *
 * Created on September 8, 2007, 6:02 PM
 *
 * To change this template, choose Tools | Template Manager
 * and open the template in the editor.
 */

package com.google.projects.chai.util;

import org.apache.xmlrpc.XmlRpcException;

/**
 * Denotes an XML-RPC fault. XML-RPC faults resemble exceptions. Requests end
 * either with a return value or a fault, the former indicatin success, and the
 * latter representing a thrown exception.
 * <p>
 * Faults have two fields: a numeric code and a human readable fault message.
 * Within the program, they also have a symbolic representation, like
 * <code>E_USEREXISTS</code>. Generally, fault codes should be used by
 * application code (on both the client and server) to identify the causes of
 * failures.
 * <p>
 * <strong>There are currently no guarantees about the over-the-wire stability
 * of this interface.</strong> That is, the mapping of error codes to actual 
 * errors may change while we're still developing. After 1.0, we might want to 
 * stabilize this interface so we can more easily work across different 
 * verisons. But while we're getting started, it's convenient to use the 
 * built-in <code>ordinal()</code> for the implementation of 
 * <code>getCode()</code>, yet we might want to change the ordering of these
 * errors.
 *
 * @author dap
 */

public enum ErrorCode {
        E_NOERR("success"), /* should not be used, but neither should errno 0 */
        
        /* general errors */
        E_NOIMPL("not yet implemented"),
        
        /* argument errors */
        E_NOVAL("no value specified for required parameter"),
        E_BADVAL("invalid value"),
        
        /* semantic errors */
        E_USEREXISTS("username already exists"),
        E_NOSUCHUSER("no such user found");
        
        
        private String text;
        private ErrorCode(String text) {
                this.text = text;
        }
        
        /** @return the XML-RPC fault code corresponding to this error */
        public int getCode() {
                return (this.ordinal());
        }
        
        /** 
         * @return the human-readable XML-RPC fault string corresponding to 
         *      this error
         */
        public String getString() {
                return (this.text);
        }
        
        /**
         * Creates an XML-RPC exception for this error. Throw the result of 
         * this method when the corresponding error occurs.
         * @return an XML-RPC exception for this error
         */
        public XmlRpcException getException() {
                return (new XmlRpcException(getCode(), getString()));
        }
        
        /**
         * Creates an XML-RPC exception for this error, with the given Throwable
         * linked to it.
         * @see #getException()
         */
        public XmlRpcException getException(Throwable t) {
                return (new XmlRpcException(getCode(), getString(), t));
        }
}
